# Semantq Grammar Documentation
Semantq is a lightweight, expressive grammar and declarative syntax for writing Semantq JS Framework components with dynamic capabilities. It supports standard HTML elements, logic blocks, event handlers, and custom attributes. This is the documentation of the syntax and features supported by the Semantq grammar.
---
## Table of Contents
1. [HTML Elements](#html-elements)
- [Open and Close Tags](#open-and-close-tags)
- [Self-Closing Tags](#self-closing-tags)
2. [Logic Blocks](#logic-blocks)
- [Conditional Blocks (`@if`)](#conditional-blocks)
3. [Event Handlers](#event-handlers)
4. [Dynamic Content](#dynamic-content)
- [Mustache Syntax](#mustache-syntax)
- [Ternary Operator](#ternary-operator)
5. [Slot Prop Attributes](#slot-prop-attributes)
6. [Examples](#examples)
7. [Grammar Rules](#grammar-rules)
8. [Usage](#usage)
9. [License](#license)
---
## HTML Elements
### Open and Close Tags
Semantq supports standard HTML open and close tags. For example:
```html
This is a paragraph inside a div.
```
### Self-Closing Tags
Self-closing HTML elements are also supported. For example:
```html
```
---
## Logic Blocks
### Conditional Blocks
Semantq supports conditional logic using the `@if` block. The syntax is as follows:
```html
@if(condition)
@endif
```
#### Example
```html
@if(isAdmin > 2)
Clicked: {counter > 1 ? 'times' : 'time'}
@endif
```
- The `condition` is a JavaScript-like expression.
- The content inside the block is rendered only if the condition evaluates to `true`.
---
## Event Handlers
Event handlers are defined using the `@` symbol followed by the event name. The handler is specified using mustache syntax (`{...}`).
#### Syntax
```html
```
#### Example
```html
```
- `@click` is the event handler for the `click` event.
- `{rejuice}` is the function or expression to execute when the event is triggered.
---
## Dynamic Content
### Mustache Syntax
Dynamic content is embedded in templates using mustache syntax (`{...}`). This allows you to inject variables or expressions directly into the HTML.
#### Example
```html
This is some sample content: {counter} - there we go!
```
### Ternary Operator
The ternary operator (`? :`) is supported for conditional rendering within mustache syntax.
#### Example
```html
```
- If `counter > 1`, the output will be `times`.
- Otherwise, the output will be `time`.
---
## Slot Prop Attributes
Slot prop attributes are used to pass data to slots in custom components. The syntax is `let:propName`.
#### Syntax
```html
```
#### Example
```html
Age: {age}
```
---
## Examples
### Example 1: Basic HTML with Dynamic Content
```html
Welcome to my page!
This is some sample content: {counter} - there we go!
```
### Example 2: Conditional Logic and Event Handlers
```html
@if(isAdmin > 2)
Clicked: {counter > 1 ? 'times' : 'time'}
@endif
```
### Example 3: Slot Prop Attributes
```html
Name: {name} Age: {age}
```
---
## Grammar Rules
The grammar is defined using Peggy.js and supports the following constructs:
- **HTML Elements**: Open/close tags and self-closing tags.
- **Logic Blocks**: Conditional rendering with `@if`.
- **Event Handlers**: Event binding with `@event={handler}`.
- **Dynamic Content**: Mustache syntax (`{...}`) and ternary operators.
- **Slot Prop Attributes**: `let:propName` syntax for passing data to slots.
---
## Usage
To use the Semantq grammar, include the Peggy.js parser in your project and parse templates using the provided grammar rules.
```javascript
import parser from './semantq-grammar.js';
const template = `
{message}
@if(showButton)
@endif
`;
const result = parser.parse(template);
console.log(result);
```
# Semantq Grammar Blocks RoadMap
## Existing Blocks
Semantq provides a simple yet powerful syntax for handling HTML, templating, event handling, and slot composition. Below are key features with examples:
## Basic HTML Structure
Semantq supports standard HTML syntax, including nested elements.
```html
Row 1, Column 1
Row 1, Column 2
Row 2, Column 1
Row 2, Column 2
```
## Self-Closing Tags
Semantq supports self-closing tags similar to HTML:
```html
```
## Mustache Tags
Mustache syntax allows for dynamic content insertion inside elements or as standalone expressions.
```html
Hello {name}
```
```html
{name}
```
## Event Handlers
Semantq allows event handlers using the `@event` syntax:
```html
```
## Event Handler Function Calls with Parameters
Functions can be called with parameters inside event handlers.
```html
```
## Mustache Attributes
Attributes can use mustache syntax to bind dynamic values.
```html
```
## Slot Prop Attributes
Slots can expose props using `let:propName`, allowing dynamic content inside slots.
```html
{name} is {age} years old.
```
## Summary
Semantq simplifies templating and dynamic HTML generation with:
- Standard HTML elements
- Self-closing tags
- Mustache syntax for data binding
- Event handlers and function calls with parameters
- Slot-based scoped props
This makes it ideal for creating structured, dynamic content efficiently.
# Syntax Blocks to Be Added
### 1. **Logic Blocks (Loops and Conditionals)**
```html
{@endawait}
```
### 3. **Combining Logic Blocks**
You can combine these logic blocks for more complex scenarios. For example:
```html
{@if items.length > 0}
{@for item in items}
{item.name}
{@endfor}
{@else}
No items found.
{@endif}
```
### 4. @Each Logic Block
```html
{@for item, index in items}
{index + 1}. {item.name}
{@endfor}
```
### 5. **Keyed Lists**
For performance optimization, Semantq offers a `key` attribute for lists, in a fashion similar to React or SolidJS.
```html
{@for item in items key="id"}
{item.name}
{@endfor}
```
- **Rationale?**
- Helps with efficient DOM updates by tracking items by a unique key.
- Keeps the syntax simple and declarative.
### 6. **Async Blocks with Fallbacks**
For async blocks, you can provide a fallback UI while waiting for data.
#### Proposed Syntax:
```html
{@await fetchData()}
Loading...
{@then data}
{data}
{@catch error}
Error: {error.message}
{@else}
No data available.
{@endawait}
```
- **Rationale**
- Adds an optional `@else` block for cases where no data is returned.
- Makes it easy to handle all possible states (loading, success, error, empty).
### Semantq Syntax Philosophy:
Consistency, intuition, flexibility, elegance and efficiency.
---
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
```
---
## Logic Blocks
### Conditional Blocks
Semantq supports conditional logic using the `@if` block. The syntax is as follows:
```html
@if(condition)
@endif
```
#### Example
```html